API Reference

The Stripe API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can use the Stripe API in test mode, which does not affect your live data or interact with the banking networks. The API key you use to authenticate the request determines whether the request is live mode or test mode.

The Stripe API differs for every account as we release new versions and tailor functionality. Log in to see docs customized to your version of the API, with your test key and data.

Subscribe to Stripe's API announce mailing list for updates.

Just getting started?

Check out our development quickstart guide.

Not a developer?

Use apps from our partners to get started with Stripe and to do more with your Stripe account—no code required.

https://api.stripe.com

pip install stripe

stripe-python

Authentication

The Stripe API uses API keys to authenticate requests. You can view and manage your API keys in the Stripe Dashboard.

Test mode secret keys have the prefix sk_test_ and live mode secret keys have the prefix sk_live_. Alternatively, you can use restricted API keys for granular permissions.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

To use your API key, assign it to stripe.api_key. The Python library will then automatically send this key in each request.

You can also set a per-request key with an option. This is often useful for Connect applications that use multiple API keys during the lifetime of a process. Methods on the returned object reuse the same API key.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

1
2
import stripe
stripe.api_key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

1
2
3
4
5
6
import stripe
charge = stripe.Charge.retrieve(
  "ch_1GlhJa2eZvKYlo2CqesHMAYC",
  api_key="sk_test_4eC39HqLyjWDarjtT1zdp7dc"
)
charge.save() # Uses the same API Key.

A sample test API key is included in all the examples here, so you can test any example right away.

To test requests using your account, replace the sample API key with your actual API key or sign in.

Connected Accounts

Clients can make requests as connected accounts using the special header Stripe-Account which should contain a Stripe account ID (usually starting with the prefix acct_).

The value is set per-request as shown in the adjacent code sample. Methods on the returned object reuse the same account ID.

1
2
3
4
5
6
import stripe
charge = stripe.Charge.retrieve(
  "ch_1GlhJa2eZvKYlo2CqesHMAYC",
  stripe_account="acct_1032D82eZvKYlo2C"
)
charge.save() # Uses the same account.

Errors

Stripe uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with Stripe's servers (these are rare).

Some 4xx errors that could be handled programmatically (e.g., a card is declined) include an error code that briefly explains the error reported.

Attributes

type string
The type of error returned. One of api_connection_error, api_error, authentication_error, card_error, idempotency_error, invalid_request_error, or rate_limit_error
code string
For some errors that could be handled programmatically, a short string indicating the error code reported.
decline_code string
For card errors resulting from a card issuer decline, a short string indicating the card issuer’s reason for the decline if they provide one.
message string
A human-readable message providing more details about the error. For card errors, these messages can be shown to your users.
param string
If the error is parameter-specific, the parameter related to the error. For example, you can use this to display a message near the correct form field.
payment_intent hash
The PaymentIntent object for errors returned on a request involving a PaymentIntent.
Show child attributes

More attributesExpand all

charge string
doc_url string
payment_method hash
setup_intent hash
source hash

200 - OK	Everything worked as expected.
400 - Bad Request	The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized	No valid API key provided.
402 - Request Failed	The parameters were valid but the request failed.
403 - Forbidden	The API key doesn't have permissions to perform the request.
404 - Not Found	The requested resource doesn't exist.
409 - Conflict	The request conflicts with another request (perhaps due to using the same idempotent key).
429 - Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors	Something went wrong on Stripe's end. (These are rare.)

api_connection_error	Failure to connect to Stripe's API.
api_error	API errors cover any other type of problem (e.g., a temporary problem with Stripe's servers), and are extremely uncommon.
authentication_error	Failure to properly authenticate yourself in the request.
card_error	Card errors are the most common type of error you should expect to handle. They result when the user enters a card that can't be charged for some reason.
idempotency_error	Idempotency errors occur when an `Idempotency-Key` is re-used on a request that does not match the first request's API endpoint and parameters.
invalid_request_error	Invalid request errors arise when your request has invalid parameters.
rate_limit_error	Too many requests hit the API too quickly.
validation_error	Errors triggered by our client-side libraries when failing to validate fields (e.g., when a card number or expiration date is invalid or incomplete).

Handling errors

Our Client libraries raise exceptions for many reasons, such as a failed charge, invalid parameters, authentication errors, and network unavailability. We recommend writing code that gracefully handles all possible API exceptions.

Related guide: Error Handling.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
try:
  # Use Stripe's library to make requests...
  pass
except stripe.error.CardError as e:
  # Since it's a decline, stripe.error.CardError will be caught

  print('Status is: %s' % e.http_status)
  print('Type is: %s' % e.error.type)
  print('Code is: %s' % e.error.code)
  # param is '' in this case
  print('Param is: %s' % e.error.param)
  print('Message is: %s' % e.error.message)
except stripe.error.RateLimitError as e:
  # Too many requests made to the API too quickly
  pass
except stripe.error.InvalidRequestError as e:
  # Invalid parameters were supplied to Stripe's API
  pass
except stripe.error.AuthenticationError as e:
  # Authentication with Stripe's API failed
  # (maybe you changed API keys recently)
  pass
except stripe.error.APIConnectionError as e:
  # Network communication with Stripe failed
  pass
except stripe.error.StripeError as e:
  # Display a very generic error to the user, and maybe send
  # yourself an email
  pass
except Exception as e:
  # Something else happened, completely unrelated to Stripe
  pass

Expanding Responses

Many objects allow you to request additional information as an expanded response by using the expand request parameter. This parameter is available on all API requests, and applies to the response of that request only. Responses can be expanded in two ways.

In many cases, an object contains the ID of a related object in its response properties. For example, a Charge may have an associated Customer ID. Those objects can be expanded inline with the expand request parameter. ID fields that can be expanded into objects are noted in this documentation with theexpandable label.

In some cases, such as the Issuing Card object's number and cvc fields, there are available fields that are not included in responses by default. You can request these fields as an expanded response by using the expand request parameter. Fields that can be included in an expanded response are noted in this documentation with the expandable label.

You can expand recursively by specifying nested fields after a dot (.). For example, requesting invoice.subscription on a charge will expand the invoice property into a full Invoice object, and will then expand the subscription property on that invoice into a full Subscription object.

You can use the expand param on any endpoint which returns expandable fields, including list, create, and update endpoints.

Expansions on list requests start with the data property. For example, you would expand data.customers on a request to list charges and associated customers. Many deep expansions on list requests can be slow.

Expansions have a maximum depth of four levels (so for example, when listing charges,data.invoice.subscription.default_source is the deepest allowed).

You can expand multiple objects at once by identifying multiple items in the expand array.

1
2
3
4
5
6
\Stripe\Stripe::setApiKey("sk_test_4eC39HqLyjWDarjtT1zdp7dc");

\Stripe\Charge::retrieve([
  'id' => 'ch_1GlgXj2eZvKYlo2CKISmHDvz',
  'expand' => ['customer', 'invoice.subscription'],
]);

{
  "id": "ch_1GlgXj2eZvKYlo2CKISmHDvz",
  "object": "charge",
  "customer": {
    "id": "cu_1GlgMq2eZvKYlo2Cpv6Z3Ois",
    "object": "customer",
    ...
  },
  "invoice": {
    "id": "in_1BjO2g2eZvKYlo2CZ1hP1oD9",
    "object": "invoice",
    "subscription": {
      "id": "su_1GldyO2eZvKYlo2ChKugIE6o",
      "object": "subscription",
      ...
    },
    ...
  },
  ...
}

Idempotent Requests

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. For example, if a request to create a charge does not respond due to a network connection error, you can retry the request with the same idempotency key to guarantee that no more than one charge is created.

To perform an idempotent request, provide an additional idempotency_key element to the request options.

Stripe's idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result, including 500 errors.

An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions.

Keys are eligible to be removed from the system after they're at least 24 hours old, and a new request is generated if a key is reused after the original has been pruned. The idempotency layer compares incoming parameters to those of the original request and errors unless they're the same to prevent accidental misuse.

Results are only saved if an API endpoint started executing. If incoming parameters failed validation, or the request conflicted with another that was executing concurrently, no idempotent result is saved because no API endpoint began execution. It is safe to retry these requests.

All POST requests accept idempotency keys. Sending idempotency keys in GET and DELETE requests has no effect and should be avoided, as these requests are idempotent by definition.

1
2
3
4
5
6
7
8
9
10
\Stripe\Stripe::setApiKey("sk_test_4eC39HqLyjWDarjtT1zdp7dc");

$charge = \Stripe\Charge::create([
  "amount" => 2000,
  "currency" => "usd",
  "source" => "tok_visa", // obtained with Stripe.js
  "description" => "My First Test Charge (created for API docs)"
], [
  "idempotency_key" => "q0ek91nWEhkNe2mN",
]);

Metadata

Updateable Stripe objects—including Account, Charge, Customer, PaymentIntent, Refund, Subscription, and Transfer—have a metadata parameter. You can use this parameter to attach key-value data to these Stripe objects.

You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long.

Metadata is useful for storing additional, structured information on an object. As an example, you could store your user's full name and corresponding unique identifier from your system on a Stripe Customer object. Metadata is not used by Stripe—for example, not used to authorize or decline a charge—and won't be seen by your users unless you choose to show it to them.

Some of the objects listed above also support a description parameter. You can use the description parameter to annotate a charge—with, for example, a human-readable description like 2 shirts for test@example.com. Unlike metadata, description is a single string, and your users may see it (e.g., in email receipts Stripe sends on your behalf).

Do not store any sensitive information (bank account numbers, card details, etc.) as metadata or in the description parameter.

Sample metadata use cases

Link IDs
Attach your system's unique IDs to a Stripe object, for easy lookups. For example, add your order number to a charge, your user ID to a customer or recipient, or a unique receipt number to a transfer.
Refund papertrails
Store information about why a refund was created, and by whom.
Customer details
Annotate a customer by storing an internal ID for your later use.

1
2
3
4
5
6
7
8
\Stripe\Stripe::setApiKey("sk_test_4eC39HqLyjWDarjtT1zdp7dc");

\Stripe\Charge::create([
  "amount" => 2000,
  "currency" => "usd",
  "source" => "tok_mastercard", // obtained with Stripe.js
  "metadata" => ["order_id" => "6735"]
]);

{
  "id": "ch_1GlgXj2eZvKYlo2CKISmHDvz",
  "object": "charge",
  "amount": 100,
  "amount_refunded": 0,
  "application": null,
  "application_fee": null,
  "application_fee_amount": null,
  "balance_transaction": "txn_19XJJ02eZvKYlo2ClwuJ1rbA",
  "billing_details": {
    "address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "email": null,
    "name": null,
    "phone": null
  },
  "calculated_statement_descriptor": null,
  "captured": false,
  "created": 1590175711,
  "currency": "usd",
  "customer": null,
  "description": "My First Test Charge (created for API docs)",
  "disputed": false,
  "failure_code": null,
  "failure_message": null,
  "fraud_details": {},
  "invoice": null,
  "livemode": false,
  "metadata": {
    "order_id": "6735"
  },
  "on_behalf_of": null,
  "order": null,
  "outcome": null,
  "paid": true,
  "payment_intent": null,
  "payment_method": "card_1GlgXT2eZvKYlo2CjQ4w5U5q",
  "payment_method_details": {
    "card": {
      "brand": "visa",
      "checks": {
        "address_line1_check": null,
        "address_postal_code_check": null,
        "cvc_check": "pass"
      },
      "country": "US",
      "exp_month": 8,
      "exp_year": 2021,
      "fingerprint": "Xt5EWLLDS7FJjR1c",
      "funding": "credit",
      "installments": null,
      "last4": "4242",
      "network": "visa",
      "three_d_secure": null,
      "wallet": null
    },
    "type": "card"
  },
  "receipt_email": null,
  "receipt_number": null,
  "receipt_url": "https://pay.stripe.com/receipts/acct_1032D82eZvKYlo2C/ch_1GlgXj2eZvKYlo2CKISmHDvz/rcpt_HKLEpJ7IA0o5QhQVU0CkA45ge4759zs",
  "refunded": false,
  "refunds": {
    "object": "list",
    "data": [],
    "has_more": false,
    "url": "/v1/charges/ch_1GlgXj2eZvKYlo2CKISmHDvz/refunds"
  },
  "review": null,
  "shipping": null,
  "source_transfer": null,
  "statement_descriptor": null,
  "statement_descriptor_suffix": null,
  "status": "succeeded",
  "transfer_data": null,
  "transfer_group": null
}

Pagination

All top-level API resources have support for bulk fetches via "list" API methods. For instance, you can list charges, list customers, and list invoices. These list API methods share a common structure, taking at least these three parameters: limit, starting_after, and ending_before.

Stripe utilizes cursor-based pagination via the starting_after and ending_before parameters. Both parameters take an existing object ID value (see below) and return objects in reverse chronological order. The ending_before parameter returns objects listed before the named object. The starting_after parameter returns objects listed after the named object. These parameters are mutually exclusive -- only one of starting_after orending_before may be used.

Our client libraries offer auto-pagination helpers to easily traverse all pages of a list.

Parameters

limit optional, default is 10
A limit on the number of objects to be returned, between 1 and 100.
starting_after optional
A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.
ending_before optional
A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

List Response Format

object string, value is "list"
A string describing the object type returned.
data array
An array containing the actual response elements, paginated by any request parameters.
has_more boolean
Whether or not there are more elements available after this set. If false, this set comprises the end of the list.
url string
The URL for accessing this list.

{
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    {
      "id": "cus_HKL2lYCBL9YVbV",
      "object": "customer",
      "address": null,
      "balance": 0,
      "created": 1590175036,
      "currency": "usd",
      "default_source": null,
      "delinquent": false,
      "description": null,
      "discount": null,
      "email": null,
      "invoice_prefix": "681EDE0",
      "invoice_settings": {
        "custom_fields": null,
        "default_payment_method": null,
        "footer": null
      },
      "livemode": false,
      "metadata": {},
      "name": null,
      "next_invoice_sequence": 1,
      "phone": null,
      "preferred_locales": [],
      "shipping": null,
      "sources": {
        "object": "list",
        "data": [],
        "has_more": false,
        "url": "/v1/customers/cus_HKL2lYCBL9YVbV/sources"
      },
      "subscriptions": {
        "object": "list",
        "data": [],
        "has_more": false,
        "url": "/v1/customers/cus_HKL2lYCBL9YVbV/subscriptions"
      },
      "tax_exempt": "none",
      "tax_ids": {
        "object": "list",
        "data": [],
        "has_more": false,
        "url": "/v1/customers/cus_HKL2lYCBL9YVbV/tax_ids"
      }
    },
    {...},
    {...}
  ]
}

Auto-pagination

Most of our libraries support auto-pagination. This feature easily handles fetching large lists of resources without having to manually paginate results and perform subsequent requests.

To use the auto-pagination feature in PHP, simply issue an initial "list" call with the parameters you need, then call autoPagingIterator() on the returned list object to iterate over all objects matching your initial parameters.

1
2
3
4
5
6
\Stripe\Stripe::setApiKey("sk_test_4eC39HqLyjWDarjtT1zdp7dc");

$customers = \Stripe\Customer::all(["limit" => 3]);
foreach ($customers->autoPagingIterator() as $customer) {
  // Do something with $customer
}

Request IDs

Each API request has an associated request identifier. You can find this value in the response headers, under Request-Id. You can also find request identifiers in the URLs of individual request logs in your Dashboard. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.

1
2
3
4
\Stripe\Stripe::setApiKey("sk_test_4eC39HqLyjWDarjtT1zdp7dc");

$customer = \Stripe\Customer::create();
echo $customer->getLastResponse()->headers["Request-Id"]

Versioning

When backwards-incompatible changes are made to the API, a new, dated version is released. The current version is 2020-03-02. Read our API upgrades guide to see our API changelog and to learn more about backwards compatibility.

All requests use your account API settings, unless you override the API version. The changelog lists every available version. Note that by default webhook events are structured according to your account API version, unless you set an API version during endpoint creation.

To override the API version, assign the version to the stripe.api_version property, or set it per-request as shown in the adjacent code sample. When overriding it per-request, methods on the returned object reuse the same Stripe version.

You can visit your Dashboard to upgrade your API version. As a precaution, use API versioning to test a new API version before committing to an upgrade.

1
2
\Stripe\Stripe::setApiKey("sk_test_4eC39HqLyjWDarjtT1zdp7dc");
\Stripe\Stripe::setApiVersion("2020-03-02");

1
2
3
4
5
$intent = \Stripe\PaymentIntent::retrieve(
  "pi_1DeOLR2eZvKYlo2CF6C9Snga",
  ['stripe_version' => '2020-03-02'],
);
$intent->capture();

Balance

This is an object representing your Stripe balance. You can retrieve it to see the balance currently on your Stripe account…

GET

/v1/balance

Show

Balance Transactions

Balance transactions represent funds moving through your Stripe account. They're created for every type of transaction that comes into or flows out of your Stripe account balance…

GET

/v1/balance_transactions/:id

GET

/v1/balance_transactions

Show

Charges

To charge a credit or a debit card, you create a Charge object. You can retrieve and refund individual charges as well as list all charges. Charges are identified by a unique, random ID…

  POST

/v1/charges

GET

/v1/charges/:id

  POST

/v1/charges/:id

  POST

/v1/charges/:id/capture

GET

/v1/charges

Show

Customers

Customer objects allow you to perform recurring charges, and to track multiple charges, that are associated with the same customer. The API allows you to create, delete, and update your customers. You can retrieve individual customers as well as a list of all your customers…

  POST

/v1/customers

GET

/v1/customers/:id

  POST

/v1/customers/:id

DELETE

/v1/customers/:id

GET

/v1/customers

Show

Disputes

A dispute occurs when a customer questions your charge with their card issuer. When this happens, you're given the opportunity to respond to the dispute with evidence that shows that the charge is legitimate. You can find more information about the dispute process in our Disputes and Fraud documentation…

GET

/v1/disputes/:id

  POST

/v1/disputes/:id

  POST

/v1/disputes/:id/close

GET

/v1/disputes

Show

Events

Events are our way of letting you know when something interesting happens in your account. When an interesting event occurs, we create a new Event object. For example, when a charge succeeds, we create a charge.succeeded event; and when an invoice payment attempt fails, we create an invoice.payment_failed event. Note that many API requests may cause multiple events to be created. For example, if you create a new subscription for a customer, you will receive both a customer.subscription.created event and a charge.succeeded event…

GET

/v1/events/:id

GET

/v1/events

Show

Files

This is an object representing a file hosted on Stripe's servers. The file may have been uploaded by yourself using the create file request (for example, when uploading dispute evidence) or it may have been created by Stripe (for example, the results of a Sigma scheduled query)…

  POST

https://files.stripe.com/v1/files

GET

/v1/files/:id

GET

/v1/files

Show

File Links

To share the contents of a File object with non-Stripe users, you can create a FileLink. FileLinks contain a URL that can be used to retrieve the contents of the file without authentication.

  POST

/v1/file_links

GET

/v1/file_links/:id

  POST

/v1/file_links/:id

GET

/v1/file_links

Show

Mandates

A Mandate is a record of the permission a customer has given you to debit their payment method.

GET

/v1/mandates/:id

Show

PaymentIntents

A PaymentIntent guides you through the process of collecting a payment from your customer. We recommend that you create exactly one PaymentIntent for each order or customer session in your system. You can reference the PaymentIntent later to see the history of payment attempts for a particular session…

  POST

/v1/payment_intents

GET

/v1/payment_intents/:id

  POST

/v1/payment_intents/:id

  POST

/v1/payment_intents/:id/confirm

  POST

/v1/payment_intents/:id/capture

  POST

/v1/payment_intents/:id/cancel

GET

/v1/payment_intents

Show

SetupIntents

A SetupIntent guides you through the process of setting up and saving a customer's payment credentials for future payments. For example, you could use a SetupIntent to set up and save your customer's card without immediately collecting a payment. Later, you can use PaymentIntents to drive the payment flow…

  POST

/v1/setup_intents

GET

/v1/setup_intents/:id

  POST

/v1/setup_intents/:id

  POST

/v1/setup_intents/:id/confirm

  POST

/v1/setup_intents/:id/cancel

GET

/v1/setup_intents

Show

Payouts

A Payout object is created when you receive funds from Stripe, or when you initiate a payout to either a bank account or debit card of a connected Stripe account. You can retrieve individual payouts, as well as list all payouts. Payouts are made on varying schedules, depending on your country and industry…

  POST

/v1/payouts

GET

/v1/payouts/:id

  POST

/v1/payouts/:id

GET

/v1/payouts

  POST

/v1/payouts/:id/cancel

Show

Products

Products describe the specific goods or services you offer to your customers. For example, you might offer a Standard and Premium version of your goods or service; each version would be a separate Product. They can be used in conjunction with Prices to configure pricing in Checkout and Subscriptions…

  POST

/v1/products

GET

/v1/products/:id

  POST

/v1/products/:id

GET

/v1/products

DELETE

/v1/products/:id

Show

Prices

Prices define the unit cost, currency, and (optional) billing cycle for both recurring and one-time purchases of products. Products help you track inventory or provisioning, and prices help you track payment terms. Different physical goods or levels of service should be represented by products, and pricing options should be represented by prices. This approach lets you change prices without having to change your provisioning scheme…

  POST

/v1/prices

GET

/v1/prices/:id

  POST

/v1/prices/:id

GET

/v1/prices

Show

Refunds

Refund objects allow you to refund a charge that has previously been created but not yet refunded. Funds will be refunded to the credit or debit card that was originally charged…

  POST

/v1/refunds

GET

/v1/refunds/:id

  POST

/v1/refunds/:id

GET

/v1/refunds

Show

Tokens

Tokenization is the process Stripe uses to collect sensitive card or bank account details, or personally identifiable information (PII), directly from your customers in a secure manner. A token representing this information is returned to your server to use. You should use our recommended payments integrations to perform this process client-side. This ensures that no sensitive card data touches your server, and allows your integration to operate in a PCI-compliant way…

  POST

/v1/tokens

  POST

/v1/tokens

  POST

/v1/tokens

  POST

/v1/tokens

  POST

/v1/tokens

GET

/v1/tokens/:id

Show

PaymentMethods

PaymentMethod objects represent your customer's payment instruments. They can be used with PaymentIntents to collect payments or saved to Customer objects to store instrument details for future payments…

  POST

/v1/payment_methods

GET

/v1/payment_methods/:id

  POST

/v1/payment_methods/:id

GET

/v1/payment_methods

  POST

/v1/payment_methods/:id/attach

  POST

/v1/payment_methods/:id/detach

Show

Bank Accounts

These bank accounts are payment methods on Customer objects…

  POST

/v1/customers/:id/sources

GET

/v1/bank_accounts/:id

  POST

/v1/customers/:id/sources/:id

  POST

/v1/customers/:id/sources/:id/verify

DELETE

/v1/customers/:id/sources/:id

GET

/v1/customers/:id/sources?object=bank_account

Show

Cards

You can store multiple cards on a customer in order to charge the customer later. You can also store multiple debit cards on a recipient in order to transfer to those cards later…

  POST

/v1/customers/:id/sources

GET

/v1/customers/:id/sources/:id

  POST

/v1/customers/:id/sources/:id

DELETE

/v1/customers/:id/sources/:id

GET

/v1/customers/:id/sources?object=card

Show

Sources

Source objects allow you to accept a variety of payment methods. They represent a customer's payment instrument, and can be used with the Stripe API just like a Card object: once chargeable, they can be charged, or can be attached to customers…

  POST

/v1/sources

GET

/v1/sources/:id

  POST

/v1/sources/:id

  POST

/v1/customers/:id/sources

DELETE

/v1/customers/:id/sources/:id

Show

Sessions

A Checkout Session represents your customer's session as they pay for one-time purchases or subscriptions through Checkout. We recommend creating a new Session each time your customer attempts to pay…

  POST

/v1/checkout/sessions

GET

/v1/checkout/sessions/:id

GET

/v1/checkout/sessions

GET

/v1/checkout/sessions/:id/line_items

Show

Coupons

A coupon contains information about a percent-off or amount-off discount you might want to apply to a customer. Coupons may be applied to invoices or orders. Coupons do not work with conventional one-off charges.

  POST

/v1/coupons

GET

/v1/coupons/:id

  POST

/v1/coupons/:id

DELETE

/v1/coupons/:id

GET

/v1/coupons

Show

Credit Note

Issue a credit note to adjust an invoice's amount after the invoice is finalized…

GET

/v1/credit_notes/preview

  POST

/v1/credit_notes

GET

/v1/credit_notes/:id

  POST

/v1/credit_notes/:id

GET

/v1/credit_notes/:credit_note/lines

GET

/v1/credit_notes/preview/lines

  POST

/v1/credit_notes/:id/void

GET

/v1/credit_notes

Show

Customer Balance Transaction

Each customer has a balance value, which denotes a debit or credit that's automatically applied to their next invoice upon finalization. You may modify the value directly by using the update customer API, or by creating a Customer Balance Transaction, which increments or decrements the customer's balance by the specified amount…

  POST

/v1/customers/:id/balance_transactions

GET

/v1/customers/:id/balance_transactions/:id

  POST

/v1/customers/:id/balance_transactions/:id

GET

/v1/customers/:id/balance_transactions

Show

Customer Tax IDs

You can add one or multiple tax IDs to a customer. A customer's tax IDs are displayed on invoices and credit notes issued for the customer…

  POST

/v1/customers/:id/tax_ids

GET

/v1/customers/:id/tax_ids/:id

DELETE

/v1/customers/:id/tax_ids/:id

GET

/v1/customers/:id/tax_ids

Show

Discounts

A discount represents the actual application of a coupon to a particular customer. It contains information about when the discount began and when it will end…

DELETE

/v1/customers/:id/discount

DELETE

/v1/subscriptions/:id/discount

Show

Invoices

Invoices are statements of amounts owed by a customer, and are either generated one-off, or generated periodically from a subscription…

  POST

/v1/invoices

GET

/v1/invoices/:id

  POST

/v1/invoices/:id

DELETE

/v1/invoices/:id

  POST

/v1/invoices/:id/finalize

  POST

/v1/invoices/:id/pay

  POST

/v1/invoices/:id/send

  POST

/v1/invoices/:id/void

  POST

/v1/invoices/:id/mark_uncollectible

GET

/v1/invoices/:id/lines

GET

/v1/invoices/upcoming

GET

/v1/invoices/upcoming/lines

GET

/v1/invoices

Show

Invoice Items

Sometimes you want to add a charge or credit to a customer, but actually charge or credit the customer's card only at the end of a regular billing cycle. This is useful for combining several charges (to minimize per-transaction fees), or for having Stripe tabulate your usage-based billing totals…

  POST

/v1/invoiceitems

GET

/v1/invoiceitems/:id

  POST

/v1/invoiceitems/:id

DELETE

/v1/invoiceitems/:id

GET

/v1/invoiceitems

Show

Plans

You can now model subscriptions more flexibly using the Prices API. It replaces the Plans API and is backwards compatible to simplify your migration…

  POST

/v1/plans

GET

/v1/plans/:id

  POST

/v1/plans/:id

DELETE

/v1/plans/:id

GET

/v1/plans

Show

Self-serve Portal

A session describes the instantiation of the self-serve portal for a particular customer. By visiting the self-serve portal's URL, the customer can manage their subscriptions and billing details. For security reasons, sessions are short-lived and will expire if the customer does not visit the URL. Create Sessions on-demand…

  POST

/v1/billing_portal/sessions

Show

Subscriptions

Subscriptions allow you to charge a customer on a recurring basis…

  POST

/v1/subscriptions

GET

/v1/subscriptions/:id

  POST

/v1/subscriptions/:id

DELETE

/v1/subscriptions/:id

GET

/v1/subscriptions

Show

Subscription Items

Subscription items allow you to create customer subscriptions with more than one plan, making it easy to represent complex billing relationships.

  POST

/v1/subscription_items

GET

/v1/subscription_items/:id

  POST

/v1/subscription_items/:id

DELETE

/v1/subscription_items/:id

GET

/v1/subscription_items

Show

Subscription Schedule

A subscription schedule allows you to create and manage the lifecycle of a subscription by predefining expected changes…

  POST

/v1/subscription_schedules

GET

/v1/subscription_schedules/:id

  POST

/v1/subscription_schedules/:id

  POST

/v1/subscription_schedules/:id/cancel

  POST

/v1/subscription_schedules/:id/release

GET

/v1/subscription_schedules

Show

Tax Rate

Tax rates can be applied to invoices and subscriptions to collect tax…

  POST

/v1/tax_rates

GET

/v1/tax_rates/:id

  POST

/v1/tax_rates/:id

GET

/v1/tax_rates

Show

Usage Records

Usage records allow you to report customer usage and metrics to Stripe for metered billing of subscription plans…

  POST

/v1/subscription_items/:id/usage_records

GET

/v1/subscription_items/:id/usage_record_summaries

Show

Accounts

This is an object representing a Stripe account. You can retrieve it to see properties on the account like its current e-mail address or if the account is enabled yet to make live charges…

  POST

/v1/accounts

GET

/v1/accounts/:id

  POST

/v1/accounts/:id

DELETE

/v1/accounts/:id

  POST

/v1/accounts/:id/reject

GET

/v1/accounts

  POST

/v1/login_links

Show

Account Links

Account Links are the means by which a Connect platform grants a connected account permission to access Stripe-hosted applications, such as Connect Onboarding…

  POST

/v1/account_links

Show

Application Fees

When you collect a transaction fee on top of a charge made for your user (using Connect), an Application Fee object is created in your account. You can list, retrieve, and refund application fees…

GET

/v1/application_fees/:id

GET

/v1/application_fees

Show

Application Fee Refunds

Application Fee Refund objects allow you to refund an application fee that has previously been created but not yet refunded. Funds will be refunded to the Stripe account from which the fee was originally collected…

  POST

/v1/application_fees/:id/refunds

GET

/v1/application_fees/:id/refunds/:id

  POST

/v1/application_fees/:id/refunds/:id

GET

/v1/application_fees/:id/refunds

Show

Capabilities

This is an object representing a capability for a Stripe account…

GET

/v1/accounts/:id/capabilities/:id

  POST

/v1/accounts/:id/capabilities/:id

GET

/v1/accounts/:id/capabilities

Show

Country Specs

Stripe needs to collect certain pieces of information about each account created. These requirements can differ depending on the account's country. The Country Specs API makes these rules available to your integration…

GET

/v1/country_specs

GET

/v1/country_specs/:id

Show

External Accounts

These External Accounts are transfer destinations on Account objects for Custom accounts. They can be bank accounts or debit cards…

  POST

/v1/accounts/:id/external_accounts

GET

/v1/accounts/:id/external_accounts/:id

  POST

/v1/accounts/:id/external_accounts/:id

DELETE

/v1/accounts/:id/external_accounts/:id

GET

/v1/accounts/:id/external_accounts?object=bank_account

  POST

/v1/accounts/:id/external_accounts

GET

/v1/accounts/:id/external_accounts/:id

  POST

/v1/accounts/:id/external_accounts/:id

DELETE

/v1/accounts/:id/external_accounts/:id

GET

/v1/accounts/:id/external_accounts?object=card

Show

Person

This is an object representing a person associated with a Stripe account…

  POST

/v1/accounts/:id/persons

GET

/v1/accounts/:id/persons/:id

  POST

/v1/accounts/:id/persons/:id

DELETE

/v1/accounts/:id/persons/:id

GET

/v1/accounts/:id/persons

Show

Top-ups

To top up your Stripe balance, you create a top-up object. You can retrieve individual top-ups, as well as list all top-ups. Top-ups are identified by a unique, random ID…

  POST

/v1/topups

GET

/v1/topups/:id

  POST

/v1/topups/:id

GET

/v1/topups

  POST

/v1/topups/:id/cancel

Show

Transfers

A Transfer object is created when you move funds between Stripe accounts as part of Connect…

  POST

/v1/transfers

GET

/v1/transfers/:id

  POST

/v1/transfers/:id

GET

/v1/transfers

Show

Transfer Reversals

Stripe Connect platforms can reverse transfers made to a connected account, either entirely or partially, and can also specify whether to refund any related application fees. Transfer reversals add to the platform's balance and subtract from the destination account's balance…

  POST

/v1/transfers/:id/reversals

GET

/v1/transfers/:id/reversals/:id

  POST

/v1/transfers/:id/reversals/:id

GET

/v1/transfers/:id/reversals

Show

Early Fraud Warning

An early fraud warning indicates that the card issuer has notified us that a charge may be fraudulent…

GET

/v1/radar/early_fraud_warnings/:id

GET

/v1/radar/early_fraud_warnings

Show

Reviews

Reviews can be used to supplement automated fraud detection with human expertise…

  POST

/v1/reviews/:id/approve

GET

/v1/reviews/:id

GET

/v1/reviews

Show

Value Lists

Value lists allow you to group values together which can then be referenced in rules…

  POST

/v1/radar/value_lists

GET

/v1/radar/value_lists/:id

  POST

/v1/radar/value_lists/:id

DELETE

/v1/radar/value_lists/:id

GET

/v1/radar/value_lists

Show

Value List Items

Value list items allow you to add specific values to a given Radar value list, which can then be used in rules…

  POST

/v1/radar/value_list_items

GET

/v1/radar/value_list_items/:id

DELETE

/v1/radar/value_list_items/:id

GET

/v1/radar/value_list_items

Show

Authorizations

When an issued card is used to make a purchase, an Issuing Authorization object is created. Authorizations must be approved for the purchase to be completed successfully…

GET

/v1/issuing/authorizations/:id

  POST

/v1/issuing/authorizations/:id

  POST

/v1/issuing/authorizations/:id/approve

  POST

/v1/issuing/authorizations/:id/decline

GET

/v1/issuing/authorizations

Show

Cardholders

An Issuing Cardholder object represents an individual or business entity who is issued cards…

  POST

/v1/issuing/cardholders

GET

/v1/issuing/cardholders/:id

  POST

/v1/issuing/cardholders/:id

GET

/v1/issuing/cardholders

Show

Cards

You can create physical or virtual cards that are issued to cardholders.

  POST

/v1/issuing/cards

GET

/v1/issuing/cards/:id

  POST

/v1/issuing/cards/:id

GET

/v1/issuing/cards

Show

Transactions

Any use of an issued card that results in funds entering or leaving your Stripe account, such as a completed purchase or refund, is represented by an Issuing Transaction object…

GET

/v1/issuing/transactions/:id

  POST

/v1/issuing/transactions/:id

GET

/v1/issuing/transactions

Show

Connection Token

A Connection Token is used by the Stripe Terminal SDK to connect to a reader…

  POST

/v1/terminal/connection_tokens

Show

Location

A Location represents a grouping of readers…

  POST

/v1/terminal/locations

GET

/v1/terminal/locations/:id

  POST

/v1/terminal/locations/:id

DELETE

/v1/terminal/locations/:id

GET

/v1/terminal/locations

Show

Reader

A Reader represents a physical device for accepting payment details…

  POST

/v1/terminal/readers

GET

/v1/terminal/readers/:id

  POST

/v1/terminal/readers/:id

DELETE

/v1/terminal/readers/:id

GET

/v1/terminal/readers

Show

Orders

Order objects are created to handle end customers' purchases of previously defined products. You can create, retrieve, and pay individual orders, as well as list all orders. Orders are identified by a unique, random ID…

  POST

/v1/orders

GET

/v1/orders/:id

  POST

/v1/orders/:id

  POST

/v1/orders/:id/pay

GET

/v1/orders

  POST

/v1/orders/:id/returns

Show

Order Items

A representation of the constituent items of any given order. Can be used to represent SKUs, shipping costs, or taxes owed on the order…

Show

Returns

A return represents the full or partial return of a number of order items. Returns always belong to an order, and may optionally contain a refund…

GET

/v1/order_returns/:id

GET

/v1/order_returns

Show

SKUs

Stores representations of stock keeping units. SKUs describe specific product variations, taking into account any combination of: attributes, currency, and cost. For example, a product may be a T-shirt, whereas a specific SKU represents the size: large, color: red version of that shirt…

  POST

/v1/skus

GET

/v1/skus/:id

  POST

/v1/skus/:id

GET

/v1/skus

DELETE

/v1/skus/:id

Show

Scheduled Queries

If you have scheduled a Sigma query, you'll receive a sigma.scheduled_query_run.created webhook each time the query runs. The webhook contains a ScheduledQueryRun object, which you can use to retrieve the query results.

GET

/v1/sigma/scheduled_query_runs/:id

GET

/v1/sigma/scheduled_query_runs

Show

Report Runs

The Report Run object represents an instance of a report type generated with specific run parameters. Once the object is created, Stripe begins processing the report. When the report has finished running, it will give you a reference to a file where you can retrieve your results. For an overview, see API Access to Reports…

  POST

/v1/reporting/report_runs

GET

/v1/reporting/report_runs/:id

GET

/v1/reporting/report_runs

Show

Report Types

The Report Type resource corresponds to a particular type of report, such as the "Activity summary" or "Itemized payouts" reports. These objects are identified by an ID belonging to a set of enumerated values. See API Access to Reports documentation for those Report Type IDs, along with required and optional parameters…

GET

/v1/reporting/report_types/:id

GET

/v1/reporting/report_types

Show

Webhook Endpoints

You can configure webhook endpoints via the API to be notified about events that happen in your Stripe account or connected accounts…

  POST

/v1/webhook_endpoints

GET

/v1/webhook_endpoints/:id

  POST

/v1/webhook_endpoints/:id

GET

/v1/webhook_endpoints

DELETE

/v1/webhook_endpoints/:id

Show

API Reference

Authentication

Connected Accounts

Errors

Attributes

type string

code string

decline_code string

message string

param string

payment_intent hash

Show child attributes

More attributesExpand all

charge string

doc_url string

payment_method hash

setup_intent hash

source hash

Handling errors

Expanding Responses

Idempotent Requests

Metadata

Sample metadata use cases

Link IDs

Refund papertrails

Customer details

Pagination

Parameters

limit optional, default is 10

starting_after optional

ending_before optional

List Response Format

object string, value is "list"

data array

has_more boolean

url string

Auto-pagination

Request IDs

Versioning

Balance

Balance Transactions

Charges

Customers

Disputes

Events

Files

File Links

Mandates

PaymentIntents

SetupIntents

Payouts

Products

Prices

Refunds

Tokens

PaymentMethods

Bank Accounts

Cards

Sources

Sessions

Coupons

Credit Note

Customer Balance Transaction

Customer Tax IDs

Discounts

Invoices

Invoice Items

Plans

Self-serve Portal

Subscriptions

Subscription Items

Subscription Schedule

Tax Rate

Usage Records

Accounts

Account Links

Application Fees

Application Fee Refunds

Capabilities

Country Specs